Inside Macintosh: More Macintosh Toolbox
Previous | Chapter Top | Chapter Contents | Next |
This section discusses routines that simplify the process of calling subroutines within your component.
When an application requests service from your component, your component receives a component parameters record containing the information for that request. That component parameters record contains the parameters that the application provided when it called your component. Your component can use this record to access the parameters directly. Alternatively, you can use the routines described in this section to extract those parameters and pass them to a subroutine of your component. By taking advantage of these routines, you can simplify the structure of your component code. For more information about the interface between the Component Manager and your component, see "Creating Components," .
Use the CallComponentFunction function to call a component subroutine without providing it access to global data for that connection. Use the CallComponentFunctionWithStorage function to call a component subroutine and to pass it a handle to the memory that stores the global data for that connection.
The CallComponentFunction function invokes a specified function of your component with the parameters originally provided by the application that called your component. You pass these parameters by specifying the same component parameters record passed to your component's main entry point.
FUNCTION CallComponentFunction (params: ComponentParameters;
func: ComponentFunction): LongInt;
CallComponentFunction returns the value that is returned by the routine referred to by the func parameter. Your component should use this value to set the current error for this connection.
If your component subroutine does not need global data, your component should use CallComponentFunction . If your component subroutine requires memory in which to store global data for the component, your component must use CallComponentFunctionWithStorage , which is described next.
For an example that uses CallComponentFunction , see Listing 5 . You can use the SetComponentInstanceError procedure, described on SetComponentInstanceError , to set the current error.
The CallComponentFunctionWithStorage function invokes a specified function of your component with the parameters originally provided by the application that called your component. You pass these parameters by specifying the same component parameters record that was received by your component's main entry point. The CallComponentFunctionWithStorage function also provides a handle to the memory associated with the current connection.
FUNCTION CallComponentFunctionWithStorage
(storage: Handle; params: ComponentParameters;
func: ComponentFunction): LongInt;
The CallComponentFunctionWithStorage function returns the value that is returned by the function referred to by the func parameter. Your component should use this value to set the current error for this connection.
CallComponentFunctionWithStorage takes as a parameter a handle to the memory associated with the connection, so subroutines of a component that don't need global data should use the CallComponentFunction routine described in the previous section instead.
If your component subroutine requires a handle to the memory associated with the connection, you must use CallComponentFunctionWithStorage . You allocate the memory for a given connection each time your component is opened. You inform the Component Manager that a connection has memory associated with it by calling the SetComponentInstanceStorage procedure.
For an example that uses CallComponentFunctionWithStorage , see Listing 5 . Use the SetComponentInstanceError procedure, described on SetComponentInstanceError , to set the current error for a connection. A description of the SetComponentInstanceStorage procedure is given next.